package reesoft.idgenerator.service.idstore;

import reesoft.idgenerator.IdGenerateException;

/**
 * 序号存储接口，存储未分配使用的最小序号
 *
 * Created by reesoft on 2017-08-28
 */
public interface IdStore
{
    /**
     * 序号缺省的初始值
     */
    long DEFAULT_INIT_VALUE = 0X1L;

    /**
     * 序号缺省的最大值
     */
    long DEFAULT_MAX_VALUE = 0X7FFFFFFFFFFFFFFFL;

    /**
     * 用缺省的初始值和最大值初始化序号存储空间
     * 如果序号不存在，初始化为 DEFAULT_INIT_VALUE(1)；序号已存在则不做任何操作
     *
     * @param name 序号的名称
     * @throws IdGenerateException 异常必须得到处理，否则后续分配序号操作将不能成功
     */
    void init(String name) throws IdGenerateException;

    /**
     * 初始化序号存储空间
     * 如果序号不存在，初始化为 initValue；序号已存在则不做任何操作
     *
     * @param name 序号的名称
     * @param initValue 初始值
     * @param maxValue 最大值
     * @throws IdGenerateException 异常必须得到处理，否则后续分配序号操作将不能成功
     */
    void init(String name, long initValue, long maxValue) throws IdGenerateException;

    /**
     * 检测是否已为序号分配存储空间
     *
     * @param name 序号的名称
     */
    boolean check(String name);

    /**
     * 从存储媒介加载、分配下一批可用的序号并变更状态
     *
     * @param name 序号的名称
     * @param amount 序号的数量
     * @return 下一批可用的序号的最小值
     * @throws IdGenerateException 如果未分配使用的最小序号加上 amount 超过序号的最大值，抛出异常信息为 Exceed max value
     */
    long loadAndIncrease(String name, long amount) throws IdGenerateException;
}
